 (Disk 2).iso/pc/technical publications/quicktime/qtdevdocs/images/qtsmban.gif){kind=small}
 (Disk 2).iso/pc/technical publications/quicktime/qtdevdocs/images/qt4api.gif)
3D Graphics Programming with QuickDraw 3D 1.5.4
Previous | QD3D Book | Overview | Chapter Contents | Next |
Creating and Managing Controllers
QuickDraw 3D provides routines that you can use to create and manipulate controller objects.
Some of these functions are intended for use only by controller device drivers. You should not call those functions from within applications.
Q3Controller_New
You can use the Q3Controller_New function to create a new controller.
TQ3ControllerRef Q3Controller_New (
const TQ3ControllerData *controllerData);
DESCRIPTION
The Q3Controller_New function returns, as its function result, a reference to a new controller object having the characteristics specified by the controllerData parameter. The new controller object is initially made active and is associated with the system cursor's tracker. You can call Q3Controller_SetTracker to associate the controller with some other tracker. The serial number of the new controller object is set to 1. If Q3Controller_New cannot create a new controller, it returns NULL .
You cannot delete a controller, but you can make it no longer operational. See the description of Q3Controller_Decommission ( [link] ) for details.
SPECIAL CONSIDERATIONS
In general, you need to use this function only if you are writing a device driver for a controller.
SEE ALSO
See "Controller Data Structure" for a description of the fields of the controller data structure.
Q3Controller_GetListChanged
You can use the Q3Controller_GetListChanged function to determine whether the list of available controllers has changed.
TQ3Status Q3Controller_GetListChanged (
TQ3Boolean *listChanged,
unsigned long *serialNumber);
- listChanged
- On exit, a Boolean value that indicates whether the list of available controllers has changed ( kQ3True ) or not ( kQ3False ).
- serialNumber
- On entry, a serial number of the list of available controllers. On exit, the current serial number of that list.
DESCRIPTION
The Q3Controller_GetListChanged function returns, in the listChanged parameter, a Boolean value that indicates whether the list of available controllers has changed since the time the serial number passed in the serialNumber parameter was generated. If the list has changed, the new serial number is returned in the serialNumber parameter; otherwise, the serialNumber parameter is unchanged.
Q3Controller_Next
You can use the Q3Controller_Next function to read through the list of available controllers.
TQ3Status Q3Controller_Next (
TQ3ControllerRef controllerRef,
TQ3ControllerRef *nextControllerRef);
- controllerRef
- A reference to a controller, or NULL .
- nextControllerRef
- On exit, a reference to the controller that immediately follows the specified controller. If the value in the controllerRef parameter is NULL , this parameter returns a reference to the first controller.
DESCRIPTION
The Q3Controller_Next function returns, in the nextControllerRef parameter, a reference to the controller that immediately follows the controller specified by the controllerRef parameter. To get the first controller in the list, pass the value NULL in the controllerRef parameter. If the controller specified by the controllerRef parameter is the last controller in the list, nextControllerRef is set to NULL .
Q3Controller_Decommission
You can use the Q3Controller_Decommission function to make a controller inactive.
TQ3Status Q3Controller_Decommission (TQ3ControllerRef controllerRef);
DESCRIPTION
The Q3Controller_Decommission function makes the controller specified by the controllerRef parameter inactive. Any remaining references to a controller that has been decommissioned are still valid, but the controller is no longer operational. (In other words, when the specified controller is referred to by an application or process other than the one that created it, reasonable default values are returned, not kQ3Failure .) Decommissioning a controller might cause the notify function of the tracker currently associated with the specified controller to be called.
Q3Controller_GetActivation
You can use the Q3Controller_GetActivation function to get the activation state of a controller.
TQ3Status Q3Controller_GetActivation (
TQ3ControllerRef controllerRef,
TQ3Boolean *active);
Q3Controller_SetActivation
You can use the Q3Controller_SetActivation function to set the activation state of a controller.
TQ3Status Q3Controller_SetActivation (
TQ3ControllerRef controllerRef,
TQ3Boolean active);
- controllerRef
- A reference to a controller.
- active
- A Boolean value that indicates whether the specified controller is to be made active ( kQ3True ) or inactive ( kQ3False ).
DESCRIPTION
The Q3Controller_SetActivation function sets the activation state of the controller specified by the controllerRef parameter to the value specified in the active parameter. If the activation state of a controller is changed, the serial number of the list of available controllers is incremented. A controller should be inactive if it is temporarily off-line.
The notify function of the tracker currently associated with the specified controller might be called when Q3Controller_SetActivation is called.
Q3Controller_GetSignature
You can use the Q3Controller_GetSignature function to get the signature of a controller.
TQ3Status Q3Controller_GetSignature (
TQ3ControllerRef controllerRef,
char *signature,
unsigned long numChars);
- controllerRef
- A reference to a controller.
- signature
- On entry, a pointer to a buffer that is to be filled with the signature of the specified controller.
- numChars
- On entry, the size of the buffer pointed to by the signature parameter.
DESCRIPTION
The Q3Controller_GetSignature function returns, through the signature parameter, the signature of the controller specified by the controllerRef parameter. You are responsible for allocating a buffer whose address is passed in the signature parameter and whose size is passed in the numChars parameter. If the signature is larger than the specified size, the signature is truncated to fit in the buffer.
Q3Controller_GetChannel
You can use the Q3Controller_GetChannel function to get a controller channel.
TQ3Status Q3Controller_GetChannel (
TQ3ControllerRef controllerRef,
unsigned long channel,
void *data,
unsigned long *dataSize);
- controllerRef
- A reference to a controller.
- channel
- An index into the list of channels associated with the specified controller. This value is always greater than or equal to 0 and less than the channel count specified at the time Q3Controller_New was called.
- data
- On exit, a pointer to the current value of the specified controller channel. The data type of the returned channel is controller-specific.
- dataSize
- On entry, the number of bytes in the specified buffer. On exit, the number of bytes actually written to that buffer.
DESCRIPTION
The Q3Controller_GetChannel function returns, through the data parameter, the current controller channel specified by the controllerRef and channel parameters. You are responsible for allocating memory for the data buffer and passing the size of that buffer in the dataSize parameter. Q3Controller_GetChannel returns, in the dataSize parameter, the number of bytes written to the data buffer.
Q3Controller_SetChannel
You can use the Q3Controller_SetChannel function to set a controller channel.
TQ3Status Q3Controller_SetChannel (
TQ3ControllerRef controllerRef,
unsigned long channel,
const void *data,
unsigned long dataSize);
- controllerRef
- A reference to a controller.
- channel
- An index into the list of channels associated with the specified controller. This value is always greater than or equal to 0 and less than the channel count specified at the time Q3Controller_New was called.
- data
- On entry, a pointer to a buffer that contains the desired value of the specified controller channel. The data type of the channel is controller-specific. If this field contains the value NULL , the specified channel is reset to a default or inactive value.
- dataSize
- On entry, the number of bytes of data in the specified buffer.
Q3Controller_GetValueCount
You can use the Q3Controller_GetValueCount function to get the number of values of a controller.
TQ3Status Q3Controller_GetValueCount (
TQ3ControllerRef controllerRef,
unsigned long *valueCount);
Q3Controller_SetTracker
You can use the Q3Controller_SetTracker function to set the tracker associated with a controller.
TQ3Status Q3Controller_SetTracker (
TQ3ControllerRef controllerRef,
TQ3TrackerObject tracker);
DESCRIPTION
The Q3Controller_SetTracker function associates the tracker specified by the tracker parameter with the controller specified by the controllerRef parameter. If the value of the tracker parameter is NULL , the controller is attached to the system cursor tracker. Changing a controller's tracker might cause the notify functions of both the previous tracker and the new tracker to be called.
Q3Controller_HasTracker
You can use the Q3Controller_HasTracker function to determine whether a controller is currently associated with a tracker.
TQ3Status Q3Controller_HasTracker (
TQ3ControllerRef controllerRef,
TQ3Boolean *hasTracker);
Q3Controller_Track2DCursor
You can use the Q3Controller_Track2DCursor function to determine whether a controller is currently affecting the two-dimensional system cursor.
TQ3Status Q3Controller_Track2DCursor (
TQ3ControllerRef controllerRef,
TQ3Boolean *track2DCursor);
- controllerRef
- A reference to a controller.
- track2DCursor
- On exit, a Boolean value that indicates whether the specified controller is currently affecting the two-dimensional system cursor ( kQ3True ) or not ( kQ3False ).
DESCRIPTION
The Q3Controller_Track2DCursor function returns, in the track2DCursor parameter, a Boolean value that indicates whether the controller specified by the controllerRef parameter is currently affecting the two-dimensional system cursor but the z axis values and orientation of the system cursor tracker are being ignored. If the specified controller is not attached to the system cursor tracker or if that controller is inactive, track2DCursor is set to kQ3False .
Q3Controller_Track3DCursor
You can use the Q3Controller_Track3DCursor function to determine whether a controller is currently affecting the depth information also being used with the system cursor.
TQ3Status Q3Controller_Track3DCursor (
TQ3ControllerRef controllerRef,
TQ3Boolean *track3DCursor);
- controllerRef
- A reference to a controller.
- track3DCursor
- On exit, a Boolean value that indicates whether the specified controller is currently affecting the system cursor and the depth is being used ( kQ3True ) or not ( kQ3False ).
DESCRIPTION
The Q3Controller_Track3DCursor function returns, in the track3DCursor parameter, a Boolean value that indicates whether the controller specified by the controllerRef parameter is currently affecting the two-dimensional system cursor and the z axis values and orientation of the system cursor tracker are not being ignored. If the specified controller is not attached to the system cursor tracker or if that controller is inactive, track3DCursor is set to kQ3False .
Q3Controller_GetButtons
You can use the Q3Controller_GetButtons function to get the button state of a controller.
TQ3Status Q3Controller_GetButtons (
TQ3ControllerRef controllerRef,
unsigned long *buttons);
Q3Controller_SetButtons
You can use the Q3Controller_SetButtons function to set the button state of a controller.
TQ3Status Q3Controller_SetButtons (
TQ3ControllerRef controllerRef,
unsigned long buttons);
DESCRIPTION
The Q3Controller_SetButtons function sets the button state of the controller specified by the controllerRef parameter to the button state value passed in the buttons parameter. If the specified controller is inactive, Q3Controller_SetButtons has no effect. Changing a controller's button state might cause the notify function of the tracker currently associated with that controller to be called.
Q3Controller_GetTrackerPosition
You can use the Q3Controller_GetTrackerPosition function to get the position of a controller's tracker.
TQ3Status Q3Controller_GetTrackerPosition (
TQ3ControllerRef controllerRef,
TQ3Point3D *position);
- controllerRef
- A reference to a controller.
- position
- On exit, the current position of the tracker associated with the specified controller.
DESCRIPTION
The Q3Controller_GetTrackerPosition function returns, in the position parameter, the current position of the tracker associated with the controller specified by the controllerRef parameter. If no tracker is currently associated with that controller, Q3Controller_GetTrackerPosition returns the position of the system cursor's tracker. Q3Controller_GetTrackerPosition has no effect if the controller is inactive.
Q3Controller_SetTrackerPosition
You can use the Q3Controller_SetTrackerPosition function to set the position of a controller's tracker.
TQ3Status Q3Controller_SetTrackerPosition (
TQ3ControllerRef controllerRef,
const TQ3Point3D *position);
- controllerRef
- A reference to a controller.
- position
- The desired position of the tracker associated with the specified controller.
DESCRIPTION
The Q3Controller_SetTrackerPosition function changes the position of the tracker currently associated with the controller specified by the controllerRef parameter to the position specified in the position parameter. If no tracker is currently associated with that controller, Q3Controller_SetTrackerPosition changes the position of the system cursor's tracker. Q3Controller_SetTrackerPosition has no effect if the controller is inactive.
Calling Q3Controller_SetTrackerPosition might cause the notify function of the controller's tracker to be called.
Q3Controller_MoveTrackerPosition
You can use the Q3Controller_MoveTrackerPosition function to move a controller's tracker relative to its current position.
TQ3Status Q3Controller_MoveTrackerPosition (
TQ3ControllerRef controllerRef,
const TQ3Vector3D *delta);
- controllerRef
- A reference to a controller.
- delta
- A three-dimensional vector specifying a relative change in the position of the tracker associated with the specified controller.
DESCRIPTION
The Q3Controller_MoveTrackerPosition function changes the position of the tracker currently associated with the controller specified by the controllerRef parameter by the relative amount specified in the delta parameter. If no tracker is currently associated with that controller, Q3Controller_MoveTrackerPosition changes the position of the system cursor's tracker relative to its current position. Q3Controller_MoveTrackerPosition has no effect if the controller is inactive.
Calling Q3Controller_MoveTrackerPosition might cause the notify function of the controller's tracker to be called.
Q3Controller_GetTrackerOrientation
You can use the Q3Controller_GetTrackerOrientation function to get the current orientation of a controller's tracker.
TQ3Status Q3Controller_GetTrackerOrientation (
TQ3ControllerRef controllerRef,
TQ3Quaternion *orientation);
- controllerRef
- A reference to a controller.
- orientation
- On exit, the current orientation of the tracker associated with the specified controller.
DESCRIPTION
The Q3Controller_GetTrackerOrientation function returns, in the orientation parameter, the current orientation of the tracker associated with the controller specified by the controllerRef parameter. If no tracker is currently associated with that controller, Q3Controller_GetTrackerOrientation returns the orientation of the system cursor's tracker. Q3Controller_GetTrackerOrientation has no effect if the controller is inactive.
Q3Controller_SetTrackerOrientation
You can use the Q3Controller_SetTrackerOrientation function to set the orientation of a controller's tracker.
TQ3Status Q3Controller_SetTrackerOrientation (
TQ3ControllerRef controllerRef,
const TQ3Quaternion *orientation);
- controllerRef
- A reference to a controller.
- orientation
- The desired orientation of the tracker associated with the specified controller.
DESCRIPTION
The Q3Controller_SetTrackerOrientation function changes the orientation of the tracker currently associated with the controller specified by the controllerRef parameter to the orientation specified in the orientation parameter. If no tracker is currently associated with that controller, Q3Controller_SetTrackerOrientation changes the orientation of the system cursor's tracker. Q3Controller_SetTrackerOrientation has no effect if the controller is inactive.
Calling Q3Controller_SetTrackerOrientation might cause the notify function of the controller's tracker to be called.
Q3Controller_MoveTrackerOrientation
You can use the Q3Controller_MoveTrackerOrientation function to reorient a controller's tracker relative to its current orientation.
TQ3Status Q3Controller_MoveTrackerOrientation (
TQ3ControllerRef controllerRef,
const TQ3Quaternion *delta);
- controllerRef
- A reference to a controller.
- delta
- The desired relative change in the orientation of the tracker associated with the specified controller.
DESCRIPTION
The Q3Controller_MoveTrackerOrientation function changes the orientation of the tracker currently associated with the controller specified by the controllerRef parameter by the relative amount specified in the delta parameter. If no tracker is currently associated with that controller, Q3Controller_MoveTrackerOrientation changes the orientation of the system cursor's tracker relative to its current orientation. Q3Controller_MoveTrackerOrientation has no effect if the controller is inactive.
Calling Q3Controller_MoveTrackerOrientation might cause the notify function of the controller's tracker to be called.
Q3Controller_GetValues
You can use the Q3Controller_GetValues function to get the list of values of a controller.
TQ3Status Q3Controller_GetValues (
TQ3ControllerRef controllerRef,
unsigned long valueCount,
float *values,
TQ3Boolean *changed,
unsigned long *serialNumber);
- controllerRef
- A reference to a controller.
- valueCount
- The number of elements in the array pointed to by the values parameter.
- values
- On entry, a pointer to an array of controller values. The size of the array is determined by the number of elements in the array (as specified by the valueCount parameter) and the size of a controller value (which is controller-dependent).
- changed
- On exit, a Boolean value that indicates whether the specified array of values was changed ( kQ3True ) or not ( kQ3False ).
- serialNumber
- On entry, a controller serial number, or NULL .
DESCRIPTION
The Q3Controller_GetValues function returns, in the values parameter, a pointer to an array that contains the current values for the controller specified in the controllerRef parameter. The valueCount parameter specifies the number of elements in the array (which you must already have allocated). Q3Controller_GetValues might fill in fewer elements if the controller does not support the specified number of values.
If the value of the serialNumber parameter is NULL , Q3Controller_GetValues fills in the values array and returns the value kQ3True in the changed parameter. Otherwise, the value specified in the serialNumber parameter is compared with the controller's current serial number. If the two serial numbers are identical, Q3Controller_GetValues leaves the values array and the serialNumber parameter unchanged and returns the value kQ3False in the changed parameter. If the two serial number differ, Q3Controller_GetValues fills in the values array, updates the serialNumber parameter, and returns the value kQ3True in the changed parameter.
If the specified controller is inactive, the values array and the changed parameter are unchanged.
Q3Controller_SetValues
You can use the Q3Controller_SetValues function to set the list of values of a controller.
TQ3Status Q3Controller_SetValues (
TQ3ControllerRef controllerRef,
const float *values,
unsigned long valueCount);
- controllerRef
- A reference to a controller.
- values
- A pointer to an array of controller values. The size of the array is determined by the number of elements in the array (as specified by the valueCount parameter) and the size of a controller value (which is controller-dependent).
- valueCount
- The number of elements in the array pointed to by the values parameter.
© 1997 Apple Computer, Inc.
Previous | QD3D Book | Overview | Chapter Contents | Next |